home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / Amiga_Mail_Vol2 / Archives / Plain / nd91.lha / Notify / notify.txt < prev    next >
Encoding:
Text File  |  1991-11-18  |  10.4 KB  |  208 lines
  1. (c)  Copyright 1991 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice,
  3. and is provided "as is" without warranty of any kind, either expressed
  4. or implied.  The entire risk as to the use of this information is
  5. assumed by the user.
  6.  
  7.  
  8. Notification
  9.  
  10. by Ewout Walraven
  11.  
  12.  
  13. File Notification is a form of interprocess communication available under
  14. Release 2.0.  An application can ask a file system (like the RAM disk handler
  15. RAM:, df0:, df1:...) that supports notification to inform it whenever changes
  16. are made to a specific file or directory, making it easy for the application
  17. to react to such changes.  The V37 ROM file system and the V37 and V36 RAM
  18. disk handler support file notification.
  19.  
  20. Under Release 2.0, the preferences control program, IPrefs, sets up
  21. notification on most of the preferences files in ENV:sys.  If the user alters
  22. any of these files (which he/she normally does with a preferences editor),
  23. the system will notify IPrefs about the change. IPrefs will react to this
  24. notification by attempting to alter the user's environment to reflect the
  25. preference change.  For example, if the user opens the ScreenMode preferences
  26. editor and alters the Workbench environment so that the Workbench screen
  27. should be a Hires NTSC screen, ScreenMode writes a file called
  28. Screenmode.prefs to the ENV:sys directory which happens to be in RAM:.
  29. Because IPrefs has set up notification on this file, the RAM disk file system
  30. will notify IPrefs of the change, IPrefs will read in the Screenmode.prefs
  31. file and will try to reset the Workbench screen so it is in Hires NTSC mode.
  32.  
  33. Notification allows very different applications to share common data files
  34. without knowing anything about each other.  This has many possible uses in
  35. the Amiga's single user, multitasking environment.  One possible use for
  36. notification is in a desktop publishing (DTP) package.  The user can open the
  37. DTP package to layout a group of ILBMs, some structured drawings, and word
  38. processed text.  When the user loads each of these, the DTP package sets up
  39. notification on each of their corresponding files.  If the user loads an
  40. appropriate editor and changes any of the files on which the DTP package has
  41. set up notification, the DTP package will receive notification of these
  42. changes and can automatically re-import these files into the current DTP
  43. document without the user having to intervene.  Another possible use for
  44. notification might be in a make utility.  A make program for a compiler could
  45. set up notification on a set of source code and object files.  If any of
  46. those files change, the make program will recompile and link the program,
  47. without the programmer having to intervene.
  48.  
  49. Setting up file notification on a file is easy.  The StartNotify() function
  50. from dos.library starts notification on a file or directory:
  51.  
  52. BOOL StartNotify( struct NotifyRequest *notify );
  53.  
  54. StartNotify() returns DOSTRUE if the call is successful, or it returns DOSFALSE (for example, when the file's file system does not
  55. support notification).  This function takes a pointer to an initialized NotifyRequest structure as its only argument (as defined in
  56. <dos/notify.h>):
  57.  
  58. struct NotifyRequest {
  59.     UBYTE *nr_Name;     /* File/directory name for which you want notification */
  60.     UBYTE *nr_FullName; /* Used by DOS. Do not use */
  61.     ULONG nr_UserData;  /* For applications use */
  62.     ULONG nr_Flags;     /* Flags indicating Signal or Message notification */
  63.  
  64.     union {
  65.         /* Used for Message notification */
  66.         struct {
  67.             struct MsgPort *nr_Port;    /* Message port to receive messages on */
  68.         } nr_Msg;
  69.         /* Used for Signal notification */
  70.         struct {
  71.             struct Task *nr_Task;       /* The task to signal */
  72.             UBYTE nr_SignalNum;         /* The signal number to use. */
  73.             UBYTE nr_pad[3];
  74.         } nr_Signal;
  75.     } nr_stuff;
  76.  
  77.     ULONG nr_Reserved[4];          /* leave 0 for now */
  78.  
  79.     /* Used internally by handlers */
  80.     ULONG nr_MsgCount;             /* number of outstanding messages */
  81.     struct MsgPort *nr_Handler;    /* handler to send to (for EndNotify) */
  82. };
  83.  
  84.  
  85. This structure must not be altered by the application while notification is
  86. in effect!
  87.  
  88. The nr_Name field contains a pointer to the name of the file on which to set
  89. up notification.  Currently, nr_Name has to be a file name and path
  90. containing a logical device name (for example df0:, work:, fonts:).  The
  91. nr_FullName field is for the private use of the file system.  Any other use
  92. of it is strictly prohibited.  The nr_UserData field is available for an
  93. applications private use.
  94.  
  95. The nr_Flags field tells the file system which type of notification to set
  96. up, message or signal.  When the file system uses message notification, it
  97. notifies an application by sending an Exec message.  An application asks a
  98. file handler to notify it via an Exec message by setting the NRF_SEND_MESSAGE
  99. flag in nr_Flags.  When the file system uses signal notification, it sets an
  100. Exec signal to notify an application.  An application receives notification
  101. via a signal by setting the NRF_SEND_SIGNAL flag.
  102.  
  103. The nr_Flags field has two other flags, NRF_WAIT_REPLY and
  104. NRF_NOTIFY_INITIAL. The NRF_WAIT_REPLY tells the file handler not to send
  105. notification messages about a specific file/directory to an application if
  106. the application has not replied to a previous notification message about that
  107. specific file.  This flag only applies to message notification.  The
  108. NRF_NOTIFY_INITIAL flag tells the file handler to notify the application if
  109. the file exists when it sets up notification on the file.  The flags for the
  110. nr_Flags field are defined in <dos/notify.h>.
  111.  
  112. The layout of the rest of the NotifyRequest structure depends on the type of
  113. notification.  If the application is using message notification, it must
  114. supply the handler with a message port to send the notification messages.
  115. The NotifyRequest.nr_stuff.nr_Msg.nr_Port field contain the pointer to the
  116. message port that will receive the message notifications.  If the application
  117. is using a signal for notification, it must supply a pointer to the task to
  118. signal and the number (not bit!) of the signal.  In this case, the
  119. NotifyRequest.nr_stuff.nr_Signal.nr_Task field should contain the appropriate
  120. task pointer and  the NotifyRequest.nr_stuff.nr_Signal.nr_SignalNum field
  121. should contain the signal number.
  122.  
  123. When a file handler uses message notification, it will send a NotifyMessage:
  124.  
  125. struct NotifyMessage {
  126.     struct Message nm_ExecMessage;
  127.     ULONG  nm_Class;               /* Class, will be NOTIFY_CLASS */
  128.     UWORD  nm_Code;                /* Code, will be NOTIFY_CODE */
  129.     struct NotifyRequest *nm_NReq; /* Pointer to the NotifyRequest you supplied */
  130.     ULONG  nm_DoNotTouch;          /* private */
  131.     ULONG  nm_DoNotTouch2;         /* private */
  132. };
  133.  
  134. Message notification is especially useful if you are monitoring more than one
  135. file.  It quickly enables you to find out which file/directory caused this
  136. message by either comparing the NotifyRequest structure returned in nm_NReq
  137. with the one you sent in the StartNotify() function, or by reading the
  138. NotifyRequest's nr_UserData field.  Because the NotifyMessage's nm_Class and
  139. nm_Code fields contain values that distinguish it from other types of
  140. messages, you can use an already allocated message port (from a window for
  141. example) to receive notification messages.
  142.  
  143. To end notification on a file, use the dos.library function EndNotify():
  144.  
  145. void EndNotify( struct NotifyRequest *notify );
  146.  
  147. An application must call this function for each of its successful
  148. StartNotify() calls.  This function takes one parameter, a pointer to the
  149. NotifyRequest structure that the application used to initiate the
  150. notification.  In the case of message notification, EndNotify() will remove
  151. all pending notify messages from your message port.  After calling this
  152. function, it is safe for the application to change or free the NotifyRequest
  153. structure.  The application may also remove the message port or free the
  154. signal bit.
  155.  
  156. A file handler should send notification when it receives any of the following
  157. packets (from <dos/dosextens.h>) about the notification file or directory:
  158.  
  159.         ACTION_RENAME_OBJECT
  160.         ACTION_RENAME_DISK
  161.         ACTION_CREATE_DIR
  162.         ACTION_DELETE_OBJECT
  163.  
  164.         ACTION_WRITE
  165.         ACTION_FINDUPDATE
  166.         ACTION_FINDOUTPUT
  167.         ACTION_SET_FILE_SIZE
  168.  
  169.         ACTION_SET_DATE
  170.  
  171.  
  172. The first four packets will cause notification immediately.  The second four
  173. packets will cause notification when the notification file is closed.  The
  174. last packet, ACTION_SET_DATE, should cause notification immediately, but due
  175. to a bug in the V37 ROM file system, only the RAM disk's file handler (RAM:)
  176. will send notification.
  177.  
  178. Notice that some of the packets that trigger a notification are sent by a
  179. process when it is trying to create a new file or directory.  A file system
  180. that supports notification should be able to set up notification on a file or
  181. directory that does not currently exist.  A file system should send
  182. notification when it creates that file or directory.
  183.  
  184. Note however that, although notification on directories is part of the OS in
  185. release 2.0, it does not work correctly.  In the ROM file system, directory
  186. notification only works if that directory exists when notification is set up.
  187. If your application tries to set up notification on a ROM file system
  188. directory before the directory exists, your application will never receive
  189. notification about that directory.  If notification is set up for a directory
  190. in RAM:, you will only be informed when that directory is created or deleted
  191. and when files are created in that directory, not when files are changed or
  192. deleted.
  193.  
  194. When implementing notification in your application, there are several things
  195. to remember.  Not every file system supports notification, in particular,
  196. most network file systems will not support notification.  For this reason, no
  197. application should require notification to function.
  198.  
  199. At the end of this article are two examples for file notification.
  200. SignalNotification.c implements signal notification on a single target.
  201. MessageNotification.c shows how to start message notification on multiple
  202. targets.  Note that these examples are not linked with startup code (like
  203. c.o).  Although these examples do set up SysBase and DosBase to gain access
  204. to exec.library and dos.library, the examples do not handle the startup
  205. message (WBenchMsg) that Workbench sends when it launches an application, so
  206. do not run these examples from Workbench.
  207.  
  208.